home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / amos / intuiextend16.lha / bonus / makelib / Make_lib.doc < prev    next >
Text File  |  1980-01-04  |  11KB  |  579 lines
  1. ---------------------------------------------------------------------
  2.  
  3.                             MAKE LIB functions
  4.  
  5. ---------------------------------------------------------------------
  6.  
  7.     1. Why Make Lib was made ?
  8.  
  9.     Well, my opinion is that AMOSPro is missing usable memory
  10.     allocation routines and it doesn't have any routines to
  11.     handle lists and nodes at all. So when I was in need of
  12.     those I decided to code my own AMOSPro library.
  13.  
  14.     Make Lib includes most of list operating routines and many
  15.     memory allocating routines to make your programs more system
  16.     friendly as you can easily allocate memory blocks which are
  17.     of needed size ONLY without using clumsy AMOS banks 
  18.     routines. With malloc you can also make nifty Clean Up routine
  19.     that frees all allocated memory with only ONE function call
  20.     or even better, when you quit AMOSPro or Compiled program
  21.     Make Lib automatically frees all memory allocated with malloc.
  22.  
  23.     Lists used by Make Lib are double linked, like amiga system's
  24.     lists.
  25.  
  26.     Here's the structure of ListHeader (called List) in C format
  27.  
  28.     struct MinList {
  29.         struct MinList *mlh_Head;            (4 bytes)
  30.         struct MinList *mlh_Tail;            (4 bytes)
  31.         struct MinList *mlh_TailPred;        (4 bytes)
  32.     }
  33.  
  34.     As you can see list header is 12 bytes long and you MUST
  35.     always allocate it and call funtion Ma NewList to initialize
  36.     it.
  37.  
  38.     Here's the structure of Nodes in C format
  39.     
  40.     structure Node {
  41.         struct Node *mln_Succ;
  42.         struct Node *mln_Pred;        
  43.     }
  44.  
  45.     --- Example ---
  46.     
  47.     Rem
  48.     Rem    The structure used in this example is:
  49.     Rem
  50.     Rem    struct Node XYNode : Rem 8 bytes
  51.     Rem    UBYTE       x      : Rem 1 byte
  52.     Rem    UBYTE       y      : Rem 1 byte (= 10 bytes)
  53.     Rem
  54.  
  55.     GLOBAL XP=9:YP=10:DATASIZE=8+2
  56.  
  57.     LIST = Ma Malloc (12,$10000) : Rem Allocate List header
  58.     if (LIST)
  59.         Ma Newlist LIST
  60.     else
  61.         Edit
  62.     end if
  63.  
  64.     Rem Now List is initialized
  65.  
  66.     NODE = Ma Malloc (DATASIZE,$10000) : Rem Allocate node
  67.  
  68.     if (NODE)
  69.         Poke NODE+XP,100:Poke NODE+YP,10
  70.         Ma AddHead LIST,NODE
  71.     else
  72.         Edit
  73.     end if 
  74.  
  75.     Rem Now we have made list with one node 
  76.  
  77.     Ma Free All : Rem Let's free all allocated memory
  78.  
  79.     Edit : Rem and then to editor
  80.  
  81.     --- Example ---
  82.  
  83.  
  84.     2. Which extension ?
  85.  
  86.     The extension number of MakeLib is 17.
  87.  
  88.  
  89.     ma AllocMem
  90.  
  91.     Usage:
  92.         ptr = ma AllocMem (size,requirements)
  93.     
  94.     Inputs:
  95.         size = Size of memblock wanted
  96.         req. = Memory requirements (same as Exec AllocMem)
  97.                  Bit 0  ($1)         = Memory Public
  98.                  Bit 1  ($2)         = Memory Chip
  99.                  Bit 2  ($4)         = Memory Fast
  100.                  Bit 16 ($10000)     = Memory Clear
  101.  
  102.     Outputs:
  103.         ptr  = pointer to memblock or 0 if not enough memory.
  104.  
  105.     ma FreeMem
  106.  
  107.     Usage:
  108.         ma FreeMem ptr,size
  109.  
  110.     Inputs:
  111.         ptr  = Memory block adress
  112.         size = Size of memory block
  113.  
  114.     Outputs:
  115.         None.
  116.  
  117.     ma NewList
  118.  
  119.     Usage:    
  120.         ma NewList list
  121.  
  122.     Inputs:
  123.         list = List to be initialized
  124.  
  125.     Outputs:
  126.         None.
  127.  
  128.     ma AddHead 
  129.  
  130.     Usage:
  131.         ma AddHead list,node
  132.  
  133.     Inputs:
  134.         list = List to be Added node to
  135.         node = Pointer to node to be added
  136.  
  137.     Outputs:
  138.         None.
  139.  
  140.     ma Remove
  141.  
  142.     Usage:
  143.         ma Remove node
  144.  
  145.     Inputs:
  146.         node = Pointer to node to be removed
  147.  
  148.     Outputs:
  149.         None.
  150.  
  151.     ma AddTail
  152.  
  153.     Usage:
  154.         ma AddTail list,node
  155.  
  156.     Inputs:
  157.         list = List to be added node to
  158.         node = Pointer to node to be added
  159.  
  160.     Outputs:
  161.         None.
  162.  
  163.     ma RemHead
  164.  
  165.     Usage:
  166.         node = ma RemHead (list)
  167.  
  168.         ma RemHead removes first node in list and returns pointer
  169.         to it.
  170.  
  171.     Inputs:
  172.         list = List to remove node from.
  173.  
  174.     Ouputs:
  175.         node = Pointer to node that was head of the list 
  176.             or 0 if list was empty.
  177.  
  178.     ma AllocVec
  179.  
  180.         ma AllocVec allocates a memoryblock and stores the size of
  181.         it. So when you need to free memoryblock you can do it by
  182.         calling ma FreeVev without the size parameter (You have no
  183.         need to store it anywhere).
  184.  
  185.     Usage:
  186.         ptr = ma AllocVec (size,requirements)
  187.  
  188.     Inputs:
  189.         size = Size of memblock wanted.
  190.         req. = Memory requirements. See Ma AllocMem.
  191.  
  192.     Ouputs:
  193.         ptr  = Pointer to memory block or 0 if not enough memory 
  194.  
  195.     ma FreeVec
  196.  
  197.     Usage:
  198.         ma FreeVec ptr
  199.  
  200.     Inputs:
  201.         ptr  = Pointer to memoryblock allocated by ma AllocVec.
  202.  
  203.     Ouputs:
  204.         None.
  205.  
  206.     ma Malloc
  207.  
  208.     Usage:
  209.         ptr = ma Malloc (size,requirements)
  210.  
  211.     Inputs:
  212.         size = Size of memblock wanted.
  213.         req. = Memory requirements. See Ma AllocMem.
  214.  
  215.     Ouputs:
  216.         ptr  = Pointer to memory block or 0 if not enough memory 
  217.  
  218.     ma Free
  219.  
  220.     Usage:
  221.         ma Free ptr
  222.  
  223.     Inputs:
  224.         ptr = Pointer to memoryblock allocated with ma malloc.
  225.  
  226.     Ouputs:
  227.         None. 
  228.  
  229.     ma Realloc
  230.  
  231.     Usage:
  232.         newptr = Ma Realloc (oldptr,newsize)
  233.  
  234.     Inputs:
  235.         ptr     = Pointer to memoryblock allocated with ma malloc.
  236.        newsize = New size for reallocated block
  237.  
  238.     Ouputs:
  239.         ptr     = Pointer to new memory block or NULL if not enough
  240.                      memory got.
  241.  
  242.     NOTE!
  243.         The Memory attributes are same for new and old ptr. So if
  244.         old memory was CHIP memory --> new memory will be CHIP too.
  245.  
  246.     NOTE!
  247.         If there's not enough memory to complete this function then
  248.        old memory block will be deleted and NULL will be returned.
  249.         When oldptr is reallocated all data that fits into new memory
  250.         block will be copied into it. If old m.block is smaller than
  251.        new then additional bytes will be cleared.
  252.  
  253.     Examples:
  254.     
  255.         MAP = Ma Malloc (512,0)    : Rem We have MAP with 512 bytes
  256.         MAP = Ma Realloc (MAP,1024) : Rem Now we have MAP with 1024 bytes +
  257.         512 bytes of old data still exists at the beginning of MAP. Bytes
  258.         over 512 are cleared to 0.
  259.  
  260.  
  261.         MAP = Ma Malloc (1024,0)
  262.         MAP = Ma Realloc (MAP,512)
  263.  
  264.          In this example we have mem block with 1024 bytes which is later
  265.         shrunk into 512 bytes. New MAP ptr contains 512 bytes of old data.
  266.  
  267.     ma Free All
  268.  
  269.     Usage:
  270.         ma Free All
  271.  
  272.         ma Free All frees all memoryblocks allocated with ma Malloc.
  273.         Very useful in cleanup code to free all memory blocks with one
  274.         command.
  275.  
  276.     Inputs:
  277.         None.
  278.  
  279.     Ouputs:
  280.         None. 
  281.  
  282.     ma Next
  283.  
  284.     Usage:
  285.         ma Next (NODE)
  286.  
  287.         Ma Next returns next node in the list or NULL if node is last.
  288.  
  289.     Inputs:
  290.         Node.
  291.  
  292.     Ouputs:
  293.         Next node or NULL is last in list or empty list. 
  294.  
  295.     ma Prev
  296.  
  297.     Usage:
  298.         ma Prev (NODE)
  299.  
  300.         Ma Prev returns previous node in the list or NULL if node 
  301.         is first.
  302.  
  303.     Inputs:
  304.         Node.
  305.  
  306.     Ouputs:
  307.         Previous node or NULL is first in list or empty list. 
  308.  
  309.     ma First
  310.  
  311.     Usage:
  312.         ma First (LIST)
  313.  
  314.         Ma First returns the very first node in the list.
  315.     
  316.     Inputs:
  317.         List.
  318.  
  319.     Ouputs:
  320.         The very first node in the list or NULL if list is empty.
  321.  
  322.     ma Last
  323.  
  324.     Usage:
  325.         ma Last (LIST)
  326.  
  327.         Ma Last returns the very last node in the list.
  328.     
  329.     Inputs:
  330.         List.
  331.  
  332.     Ouputs:
  333.         The very last node in the list or NULL if list is empty.
  334.  
  335.     ma FileLen
  336.  
  337.     Usage:
  338.         ma FileLen (Name$)
  339.  
  340.         ma FileLen  returns the file length in bytes.
  341.     
  342.     Inputs:
  343.         Name with path.
  344.  
  345.     Ouputs:
  346.         The size of file in bytes or -1 if no file present.
  347.  
  348.     ma ExtB
  349.  
  350.     Usage:
  351.         ma ExtB (value)
  352.  
  353.         ma ExtB extends byte value to long word (AMOS integer).
  354.     
  355.         Example: value = maExtB(Peek(ptr))
  356.  
  357.     Inputs:
  358.         A one byte value.
  359.  
  360.     Ouputs:
  361.         The value in longword.
  362.  
  363.     ma ExtW
  364.  
  365.     Usage:
  366.         ma ExtW (value)
  367.  
  368.         ma ExtW extends word value to long word (AMOS integer).
  369.     
  370.         Example: value = maExtW(Deek(ptr))
  371.  
  372.     Inputs:
  373.         A one word value.
  374.  
  375.     Ouputs:
  376.         The value in long word.
  377.  
  378.     ma Paste Icon
  379.  
  380.     Usage:
  381.         ma Paste Icon (x,y,icon)
  382.  
  383.         ma PasteIcon is used to draw icons on AMOS screen. ma Paste Icon
  384.         is word oriented, so x coordinate is rounded down to nearest 16
  385.         pixels.
  386.     
  387.     Inputs:
  388.         X        -X coordinate to draw icon to.
  389.         Y      -Y coordinate to draw icon to.
  390.         Icon     -Number of icon to draw 
  391.  
  392.     Ouputs:
  393.         None.
  394.  
  395.     ma Point
  396.  
  397.     Usage:
  398.         Color = ma Point (x,y)
  399.  
  400.         ma Point works exactly as AMOSPro's Point function.
  401.     
  402.     Inputs:
  403.         X        -Number of x coordinate.
  404.         Y      -Number of y coordinate.
  405.  
  406.     Ouputs:
  407.         The color under certain coordinates or -1.
  408.  
  409.     ma Plot
  410.  
  411.     Usage:
  412.          ma Plot x,y,color
  413.  
  414.         ma Plot works exactly as AMOSPro's Plot function.
  415.     
  416.     Inputs:
  417.         X        -Number of x coordinate.
  418.         Y      -Number of y coordinate.
  419.         Color -Number of color to plot.
  420.  
  421.     Ouputs:
  422.         None.    
  423.  
  424.  
  425.     Mem Chip
  426.  
  427.     Usage:
  428.          Mem Chip
  429.  
  430.          Example:
  431.             NODE = Ma Malloc (100,Mem Chip)
  432.             Rem Allocates 100 bytes of chip memory
  433.     
  434.     Inputs:
  435.         None.
  436.  
  437.     Ouputs:
  438.         Chip memory requirement.    
  439.  
  440.     Mem Fast
  441.  
  442.     Usage:
  443.          Mem Fast
  444.  
  445.          Example:
  446.             NODE = Ma Malloc (100,Mem Fast)
  447.             Rem Allocates 100 bytes of fast memory
  448.     
  449.     Inputs:
  450.         None.
  451.  
  452.     Ouputs:
  453.         Fast memory requirement.    
  454.  
  455.     Mem Public
  456.  
  457.     Usage:
  458.          Mem Publ